<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.8"/>
<title>GLFW: Oculus Rift guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
	<div class="glfwheader">
		<a href="http://www.glfw.org/" id="glfwhome">GLFW</a>
		<ul class="glfwnavbar">
			<li><a href="http://www.glfw.org/documentation.html">Documentation</a></li>
			<li><a href="http://www.glfw.org/download.html">Download</a></li>
			<li><a href="http://www.glfw.org/media.html">Media</a></li>
			<li><a href="http://www.glfw.org/community.html">Community</a></li>
		</ul>
	</div>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.8 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Modules</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Oculus Rift guide </div>  </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#rift_include">Including the LibOVR and GLFW header files</a></li>
<li class="level1"><a href="#rift_init">Initializing LibOVR and GLFW</a></li>
<li class="level1"><a href="#rift_direct">Direct HMD mode</a><ul><li class="level2"><a href="#rift_direct_create">Creating a window and context</a></li>
<li class="level2"><a href="#rift_direct_attach">Attaching the window to the HMD</a></li>
</ul>
</li>
<li class="level1"><a href="#rift_extend">Extend Desktop mode</a><ul><li class="level2"><a href="#rift_extend_detect">Detecting a HMD with GLFW</a></li>
<li class="level2"><a href="#rift_extend_create">Creating a window and context</a></li>
</ul>
</li>
<li class="level1"><a href="#rift_render">Rendering to the HMD</a><ul><li class="level2"><a href="#rift_render_sdk">SDK distortion rendering</a></li>
<li class="level2"><a href="#rift_render_custom">Client distortion rendering</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>This guide is intended to fill in the gaps between the <a href="https://developer.oculus.com/documentation/">Oculus PC SDK documentation</a> and the rest of the GLFW documentation and is not a replacement for either. It requires you to use <a class="el" href="group__native.html">native access</a> and assumes a certain level of proficiency with LibOVR, platform specific APIs and your chosen development environment.</p>
<p>While GLFW has no explicit support for LibOVR, it is tested with and tries to interoperate well with it.</p>
<dl class="section note"><dt>Note</dt><dd>Because of the speed of development of the Oculus SDK, this guide may become outdated before the next release. If this is a local copy of the documentation, you may want to check the GLFW website for updates. This revision of the guide is written against version 0.4.4 of the SDK.</dd></dl>
<h1><a class="anchor" id="rift_include"></a>
Including the LibOVR and GLFW header files</h1>
<p>Both the OpenGL LibOVR header and the GLFW native header need macros telling them what OS you are building for. Because LibOVR only supports three major desktop platforms, this can be solved with canonical predefined macros.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#if defined(_WIN32)</span></div>
<div class="line"><span class="preprocessor"> #define GLFW_EXPOSE_NATIVE_WIN32</span></div>
<div class="line"><span class="preprocessor"> #define GLFW_EXPOSE_NATIVE_WGL</span></div>
<div class="line"><span class="preprocessor"> #define OVR_OS_WIN32</span></div>
<div class="line"><span class="preprocessor">#elif defined(__APPLE__)</span></div>
<div class="line"><span class="preprocessor"> #define GLFW_EXPOSE_NATIVE_COCOA</span></div>
<div class="line"><span class="preprocessor"> #define GLFW_EXPOSE_NATIVE_NSGL</span></div>
<div class="line"><span class="preprocessor"> #define OVR_OS_MAC</span></div>
<div class="line"><span class="preprocessor">#elif defined(__linux__)</span></div>
<div class="line"><span class="preprocessor"> #define GLFW_EXPOSE_NATIVE_X11</span></div>
<div class="line"><span class="preprocessor"> #define GLFW_EXPOSE_NATIVE_GLX</span></div>
<div class="line"><span class="preprocessor"> #define OVR_OS_LINUX</span></div>
<div class="line"><span class="preprocessor">#endif</span></div>
<div class="line"></div>
<div class="line"><span class="preprocessor">#include &lt;<a class="code" href="glfw3_8h.html">GLFW/glfw3.h</a>&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;<a class="code" href="glfw3native_8h.html">GLFW/glfw3native.h</a>&gt;</span></div>
<div class="line"></div>
<div class="line"><span class="preprocessor">#include &lt;OVR_CAPI_GL.h&gt;</span></div>
</div><!-- fragment --><p>Both the GLFW and LibOVR headers by default attempt to include the standard OpenGL <code>GL/gl.h</code> header (<code>OpenGL/gl.h</code> on OS X). If you wish to use a different standard header or an <a class="el" href="context.html#context_glext_auto">extension loading library</a>, include that header before these.</p>
<h1><a class="anchor" id="rift_init"></a>
Initializing LibOVR and GLFW</h1>
<p>LibOVR needs to be initialized before GLFW. This means calling at least <code>ovr_Initialize</code>, <code>ovrHmd_Create</code> and <code>ovrHmd_ConfigureTracking</code> before <a class="el" href="group__init.html#ga317aac130a235ab08c6db0834907d85e">glfwInit</a>. Similarly, LibOVR must be shut down after GLFW. This means calling <code>ovrHmd_Destroy</code> and <code>ovr_Shutdown</code> after <a class="el" href="group__init.html#gaaae48c0a18607ea4a4ba951d939f0901">glfwTerminate</a>.</p>
<h1><a class="anchor" id="rift_direct"></a>
Direct HMD mode</h1>
<p>Direct HMD mode is the recommended display mode for new applications, but the Oculus Rift runtime currently (January 2015) only supports this mode on Windows. In direct mode the HMD is not detectable as a GLFW monitor.</p>
<h2><a class="anchor" id="rift_direct_create"></a>
Creating a window and context</h2>
<p>If the HMD is in direct mode you can use either a full screen or a windowed mode window, but full screen is only recommended if there is a monitor that supports the resolution of the HMD. Due to limitations in LibOVR, the size of the client area of the window must equal the resolution of the HMD.</p>
<p>If the resolution of the HMD is much larger than the regular monitor, the window may be resized by the window manager on creation. One way to avoid this is to make it undecorated with the <a class="el" href="window.html#window_hints_wnd">GLFW_DECORATED</a> window hint.</p>
<h2><a class="anchor" id="rift_direct_attach"></a>
Attaching the window to the HMD</h2>
<p>Once you have created the window and context, you need to attach the native handle of the GLFW window to the HMD.</p>
<div class="fragment"><div class="line">ovrHmd_AttachToWindow(hmd, <a class="code" href="group__native.html#gafe5079aa79038b0079fc09d5f0a8e667">glfwGetWin32Window</a>(window), NULL, NULL);</div>
</div><!-- fragment --><h1><a class="anchor" id="rift_extend"></a>
Extend Desktop mode</h1>
<p>Extend desktop mode is a legacy display mode, but is still (January 2015) the only available mode on OS X and Linux, as well as on Windows machines that for technical reasons do not yet support direct HMD mode.</p>
<h2><a class="anchor" id="rift_extend_detect"></a>
Detecting a HMD with GLFW</h2>
<p>If the HMD is in extend desktop mode you can deduce which GLFW monitor it corresponds to and create a full screen window on that monitor.</p>
<p>On Windows, the native display device name of a GLFW monitor corresponds to the display device name of the detected HMD as stored, in the <code>DisplayDeviceName</code> member of <code>ovrHmdDesc</code>.</p>
<p>On OS X, the native display ID of a GLFW monitor corresponds to the display ID of the detected HMD, as stored in the <code>DisplayId</code> member of <code>ovrHmdDesc</code>.</p>
<p>At the time of writing (January 2015), the Oculus SDK does not support detecting which monitor corresponds to the HMD in any sane fashion, but as long as the HMD is set up and rotated properly it can be found via the screen position and resolution provided by LibOVR. This method may instead find another monitor that is mirroring the HMD, but this only matters if you intend to change its video mode.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> i, count;</div>
<div class="line"><a class="code" href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>** monitors = <a class="code" href="group__monitor.html#ga3fba51c8bd36491d4712aa5bd074a537">glfwGetMonitors</a>(&amp;count);</div>
<div class="line"></div>
<div class="line"><span class="keywordflow">for</span> (i = 0;  i &lt; count;  i++)</div>
<div class="line">{</div>
<div class="line"><span class="preprocessor">#if defined(_WIN32)</span></div>
<div class="line">    <span class="keywordflow">if</span> (strcmp(<a class="code" href="group__native.html#gac408b09a330749402d5d1fa1f5894dd9">glfwGetWin32Monitor</a>(monitors[i]), hmd-&gt;DisplayDeviceName) == 0)</div>
<div class="line">        <span class="keywordflow">return</span> monitors[i];</div>
<div class="line"><span class="preprocessor">#elif defined(__APPLE__)</span></div>
<div class="line">    <span class="keywordflow">if</span> (<a class="code" href="group__native.html#gaf22f429aec4b1aab316142d66d9be3e6">glfwGetCocoaMonitor</a>(monitors[i]) == hmd-&gt;DisplayId)</div>
<div class="line">        <span class="keywordflow">return</span> monitors[i];</div>
<div class="line"><span class="preprocessor">#elif defined(__linux__)</span></div>
<div class="line">    <span class="keywordtype">int</span> xpos, ypos;</div>
<div class="line">    <span class="keyword">const</span> <a class="code" href="structGLFWvidmode.html">GLFWvidmode</a>* mode = <a class="code" href="group__monitor.html#gafc1bb972a921ad5b3bd5d63a95fc2d52">glfwGetVideoMode</a>(monitors[i]);</div>
<div class="line">    <a class="code" href="group__monitor.html#ga102f54e7acc9149edbcf0997152df8c9">glfwGetMonitorPos</a>(monitors[i], &amp;xpos, &amp;ypos);</div>
<div class="line"></div>
<div class="line">    <span class="keywordflow">if</span> (hmd-&gt;WindowsPos.x == xpos &amp;&amp;</div>
<div class="line">        hmd-&gt;WindowsPos.y == ypos &amp;&amp;</div>
<div class="line">        hmd-&gt;Resolution.w == mode-&gt;<a class="code" href="structGLFWvidmode.html#a698dcb200562051a7249cb6ae154c71d">width</a> &amp;&amp;</div>
<div class="line">        hmd-&gt;Resolution.h == mode-&gt;<a class="code" href="structGLFWvidmode.html#ac65942a5f6981695517437a9d571d03c">height</a>)</div>
<div class="line">    {</div>
<div class="line">        <span class="keywordflow">return</span> monitors[i];</div>
<div class="line">    }</div>
<div class="line"><span class="preprocessor">#endif</span></div>
<div class="line"><span class="preprocessor">}</span></div>
</div><!-- fragment --><h2><a class="anchor" id="rift_extend_create"></a>
Creating a window and context</h2>
<p>The window is created as a regular full screen window on the found monitor. It is usually a good idea to create a <a class="el" href="window.html#window_windowed_full_screen">windowed full screen</a> window, as the HMD will very likely already be set to the correct video mode. However, in extend desktop mode it behaves like a regular monitor and any supported video mode can be requested.</p>
<p>If other monitors are mirroring the HMD and you request a different video mode, all monitors in the mirroring set will get the new video mode.</p>
<h1><a class="anchor" id="rift_render"></a>
Rendering to the HMD</h1>
<h2><a class="anchor" id="rift_render_sdk"></a>
SDK distortion rendering</h2>
<p>If you wish to use SDK distortion rendering you will need some information from GLFW to configure the renderer. Below are the parts of the <code>ovrGLConfig</code> union that need to be filled with from GLFW. Note that there are other fields that also need to be filled for <code>ovrHmd_ConfigureRendering</code> to succeed.</p>
<p>Before configuring SDK distortion rendering you should make your context current.</p>
<div class="fragment"><div class="line">    <span class="keywordtype">int</span> width, height;</div>
<div class="line">    <span class="keyword">union </span>ovrGLConfig config;</div>
<div class="line"></div>
<div class="line">    <a class="code" href="group__window.html#ga0e2637a4161afb283f5300c7f94785c9">glfwGetFramebufferSize</a>(window, &amp;width, &amp;height);</div>
<div class="line"></div>
<div class="line">    config.OGL.Header.BackBufferSize.w = width;</div>
<div class="line">    config.OGL.Header.BackBufferSize.h = height;</div>
<div class="line"><span class="preprocessor">#if defined(_WIN32)</span></div>
<div class="line">    config.OGL.Window = <a class="code" href="group__native.html#gafe5079aa79038b0079fc09d5f0a8e667">glfwGetWin32Window</a>(window);</div>
<div class="line"><span class="preprocessor">#elif defined(__APPLE__)</span></div>
<div class="line"><span class="preprocessor">#elif defined(__linux__)</span></div>
<div class="line">    config.OGL.Disp = <a class="code" href="group__native.html#ga8519b66594ea3ef6eeafaa2e3ee37406">glfwGetX11Display</a>();</div>
<div class="line"><span class="preprocessor">#endif</span></div>
</div><!-- fragment --><p>When using SDK distortion rendering you should not swap the buffers yourself, as the HMD is updated by <code>ovrHmd_EndFrame</code>.</p>
<h2><a class="anchor" id="rift_render_custom"></a>
Client distortion rendering</h2>
<p>With client distortion rendering you are in full control of the contents of the HMD and should render and swap the buffers normally. </p>
</div></div><!-- contents -->
<address class="footer">
<p>
Last update on Mon Oct 12 2015 for GLFW 3.1.2
</p>
</address>
</body>
</html>
